Перейти к основному содержимому

6.04. Руководство по техническому обслуживанию по ГОСТ 19.508-79

Руководителю Аналитику Техническому писателю

Руководство по техническому обслуживанию

ГОСТ
Основано на ГОСТ 19.508-79.

1. Введение: ГОСТ 19.508-79 — краткий обзор

ГОСТ 19.508-79 — советский государственный стандарт из состава Единой системы программной документации (ЕСПД), принятый 11 декабря 1979 г., введён в действие с 1 января 1981 г. Он определяет требования к содержанию и оформлению документа «Руководство по техническому обслуживанию» (РТО).

🎯 Назначение стандарта

Стандарт регламентирует структуру и содержание документа, предназначенного для специалистов по техническому обслуживанию (инженеров, операторов, администраторов), эксплуатирующих тестовые и диагностические программы, используемые при обслуживании технических средств (аппаратуры, оборудования, вычислительных комплексов).

⚠ Обратите внимание: хотя ГОСТ 19.508-79 формально применяется к диагностике и тестированию оборудования, его принципы применимы и к современным программным системам, особенно в контексте:

  • мониторинга и самодиагностики (health checks),
  • процедур восстановления (recovery procedures),
  • профилактического обслуживания (preventive maintenance),
  • инструментов DevOps и SRE (например, инвентаризация, проверка целостности, регрессионные тесты инфраструктуры).

📦 Область применения

Стандарт не распространяется на:

  • пользовательские инструкции (это — ГОСТ 19.504),
  • программные документы общего назначения (ГОСТ 19.501–19.509),
  • проектную и конструкторскую документацию.

Он применим к:

  • тестовым программам (self-test, burn-in, soak tests),
  • диагностике неисправностей оборудования (memory, disk, CPU, network),
  • средствам автоматизированной проверки состояния систем.

📐 Общая структура документа по ГОСТ

РазделОбязательностьКомментарий
Титульный лист✅ ОбязательноПо ГОСТ 19.105-78
Аннотация✅ ОбязательноКраткое описание назначения и области применения РТО
Содержание✅ ОбязательноДерево разделов и подразделов с номерами страниц
Введение✅ ОбязательноНазначение РТО, перечень сопутствующих эксплуатационных документов
Общие указания✅ ОбязательноПорядок, организация и особенности проведения ТО
Требования к техническим средствам✅ ОбязательноМинимальная конфигурация оборудования для запуска программы
Описание функций✅ ОбязательноПодробное описание функциональности диагностической программы
Дополнительные разделы🟡 ОпциональноНапример: «Меры безопасности», «Аварийные ситуации», «Журналирование», «Примеры использования»

📌 Примечание:

  • Все разделы оформляются по ГОСТ 19.105-78 (требования к построению, изложению, оформлению и содержанию программных документов).
  • В современной практике вместо «технических средств» подразумевается инфраструктурная среда: серверы, ОС, сетевые интерфейсы, виртуальные/контейнеризованные окружения.
  • Стандарт не требует строго литературного качества — важна точность, однозначность и полнота информации.

2. Пошаговое руководство по составлению РТО

Ниже приведено пошаговое руководство по написанию РТО. Каждый шаг включает:

  • что делать,
  • почему это важно,
  • как оформлять (с учётом современной практики технического письма).

Шаг 1. Подготовка — сбор информации

Перед началом работы необходимо:

  • получить спецификацию диагностируемой системы (аппаратной или программной),
  • выделить функции самодиагностики или тестирования,
  • определить целевую аудиторию (например: инженер 2-й категории, SRE, техподдержка),
  • уточнить сценарии использования: штатная проверка, восстановление после сбоя, предварительная приёмка.

Шаг 2. Составьте информационную часть

Обязательные элементы:

  • Титульный лист:
    Включает наименование документа, код по ГОСТ (19.508), идентификатор системы/версии, дату, организацию-разработчика.
  • Аннотация (резюме):
    Объём — 3–5 предложений. Ответьте на вопросы:
    • Что это за документ?
    • Для какой системы/программы?
    • Кто читатель?
    • Какие операции охватывает (диагностика, калибровка, сброс)?
  • Содержание:
    Генерируется автоматически при финальной сборке (например, в Docusaurus, Confluence, или через pandoc --toc).

Шаг 3. Раздел «Введение»

Что включить:

  • Назначение РТО: «Настоящий документ предназначен для специалистов по техническому обслуживанию и содержит инструкции по диагностике и восстановлению работоспособности системы X».
  • Перечень сопутствующих документов (обязательно!):
    • Руководство оператора (ГОСТ 19.504),
    • Описание применения (ГОСТ 19.502),
    • Программа и методика испытаний (ГОСТ 19.301),
    • Техническое задание (ГОСТ 19.201),
    • Руководство администратора (если есть),
    • API Reference, OpenAPI/Swagger-спецификации (в современной практике).

Формат рекомендуется табличный:

Наименование документаОбозначениеПримечание
Руководство оператораРО-X-v2.1Версия 2.1, 2025 г.
Описание примененияОП-X-2025Используется при интеграции в ELK

Шаг 4. Раздел «Общие указания»

Ключевые подпункты:

  • Общая последовательность действий (например: «1. Подготовка → 2. Запуск диагностической процедуры → 3. Анализ результатов → 4. Принятие решений»).
  • Периодичность проведения: штатная (ежедневно), после сбоя, перед обновлением.
  • Организационные требования:
    • Требуемая квалификация персонала (например: «инженер по эксплуатации, аттестованный по программе Х»),
    • Необходимые разрешения (доступ к консоли, права sudo, MFA).
  • Особые условия: температура, ЭМ-помехи, отключение от сети и т.п. (для hardware) или изоляция окружения (для ПО — например, запуск в maintenance mode).

Шаг 5. Раздел «Требования к техническим средствам»

Фокус — на минимальные требования.
В современном контексте это требования к среде выполнения. Пример структуры:

КатегорияМинимальные требованияРекомендуемые
ОСUbuntu 22.04 LTS, ядро ≥ 5.15Ubuntu 24.04 LTS
Процессор2 ядра, x86_644+ ядер, AES-NI
Память2 ГБ ОЗУ8 ГБ ОЗУ
Дисковое пространство500 МБ свободноSSD, 5 ГБ
Сетевые интерфейсыIPv4, localhostIPv6, TLS 1.3
ЗависимостиPython 3.10+, psutil, requestsPython 3.12, виртуальное окружение
Права доступаdiag-user в группе admRBAC: role:diagnostic

Правило: указывайте версии строго (не «Python 3.x», а «Python ≥ 3.10, < 3.13»). При изменении требований — фиксируйте мажорную версию РТО.

Шаг 6. Раздел «Описание функций»

Самый объёмный и технически насыщенный раздел. Структура по ГОСТ:

  1. Максимальный состав технических средств, проверяемых программой
    → В современном понимании: поддерживаемые компоненты системы (например: БД PostgreSQL, брокер RabbitMQ, frontend-контейнеры).
    Лучше оформить в виде таблицы совместимости (см. ниже).

  2. Описание совместного функционирования технических средств и программы
    → Требуется:

    • описание workflow (например: «программа инициирует HTTP-запрос к /health, ожидает 200 OK в течение 5 с»),
    • метод обработки ошибок (логика обработки timeout, 5xx, connection refused),
    • действия при выявлении неисправности (например: «при коде 0x7E — перезапуск сервиса auth-service»).
  3. Организация входных и выходных данных
    → Укажите:

    • формат входных параметров (CLI-аргументы, env-vars, конфиг-файл),
    • структуру выходных данных (JSON schema, CLI exit codes, syslog-сообщения),
    • коды возврата:
      0 — OK (все проверки пройдены)
      1 — предупреждение (рекомендуется вмешательство)
      2 — критическая ошибка (система неработоспособна)
      3 — ошибка среды (не хватает прав/ресурсов)
  4. Описание взаимодействия устройств с программой
    → Для software-систем: это интерфейсы и сценарии взаимодействия.
    Пример:

    • «Программа diag-net опрашивает все активные сетевые интерфейсы через netlink сокет»,
    • «При обнаружении packet loss > 5% — отправляет alert в Prometheus через Pushgateway»,
    • «Результаты сохраняются в /var/log/diag/net-<timestamp>.json».

Шаг 7. Дополнительные рекомендуемые разделы (современные практики)

Хотя ГОСТ их не требует, они повышают ценность документа:

  • Меры безопасности
    (например: «Программа не должна запускаться от root. Используйте systemd с User=diag и NoNewPrivileges=yes»).
  • Журналирование и мониторинг
    (формат логов, интеграция с Grafana/Prometheus, retention policy).
  • Примеры запуска
    (CLI-команды с комментариями, скриншоты терминала — но в текстовом формате!).
  • Устранение типовых неисправностей
    (FAQ-style: «Ошибка ERR_CONN_REFUSED → проверить systemctl status netd»).

3. Типичные ошибки и как их избежать

Особенно актуально при обучении начинающих технических писателей.

ОшибкаПочему это плохоКак избежать
Размытые формулировки «программа работает на компьютере»Не позволяет воспроизвести средуУказывайте точные версии, архитектуру, зависимости. Используйте термины: x86_64, arm64/v8, glibc 2.35+.
Отсутствие кодов возвратаИнженер не знает, что делать при exit code = 255Включайте таблицу exit codes. Согласуйте с разработчиками.
Нет ссылок на другие документыЧитатель «застревает» — не знает, где искать доп. информациюВ «Введении» дайте полный перечень с обозначениями и версиями.
Смешение уровней абстракции — описание «как работает алгоритм CRC-32» в РТОРТО — не справочник разработчикаОписывайте поведение, не реализацию. «Программа проверяет контрольную сумму образа диска» — достаточно.
Нет примеровТеория без практики → ошибки при выполненииДобавляйте 1–2 рабочих примера с пояснением каждой опции.
Игнорирование безопасностиЗапуск с sudo «для удобства» → уязвимостиВыделяйте блоки «Security Note»: ⚠ Не используйте --force в production.
Однократное написание, без актуализацииДокумент устаревает быстрее, чем ПОПропишите в титуле: «Последнее обновление: 2025-11-11. Актуально для версии X v3.2.1». Завяжите на CI: если изменился CLI — запретить мердж без обновления РТО.

🔁 Правило обратной связи: каждая процедура в РТО должна быть проверена на стенде человеком, не участвовавшим в разработке.


4. Пример РТО для вымышленной системы

Система XenonCache v2.1

Распределённая система кэширования данных с встроенной самодиагностикой

📌 Пояснение: XenonCache — виртуальная система. Для целей демонстрации:

  • это stateless кэш-сервер на базе in-memory хранилища,
  • поддерживает кластеризацию, репликацию, автоматическое восстановление,
  • содержит встроенную утилиту диагностики xenon-diag (CLI + HTTP API),
  • предназначена для эксплуатации инженерами SRE-группы.

Документ оформляется строго по структуре ГОСТ 19.508-79, с дополнениями современных практик (без нарушения требований стандарта).


📄 Руководство по техническому обслуживанию

Система XenonCache, версия 2.1
Документ: РТО-XC-2.1
Дата составления: 11.11.2025
Разработчик: ООО «НейтронЛабс»


Аннотация

Настоящий документ содержит инструкции по техническому обслуживанию распределённой кэш-системы XenonCache версии 2.1 с использованием встроенной диагностической программы xenon-diag. Предназначен для инженеров по эксплуатации и SRE. Описывает порядок запуска, интерпретацию результатов, обработку ошибок и действия при выявлении неисправностей. Обеспечивает соответствие требованиям надёжности и восстанавливаемости в условиях 24/7 эксплуатации.


Содержание

  1. Введение
  2. Общие указания
  3. Требования к техническим средствам
  4. Описание функций
    4.1. Максимальный состав проверяемых технических средств
    4.2. Совместное функционирование и обработка ошибок
    4.3. Организация входных и выходных данных
    4.4. Взаимодействие устройств с программой и вывод результатов

1. Введение

Настоящее Руководство по техническому обслуживанию (РТО) предназначено для специалистов, ответственных за эксплуатацию и обслуживание распределённой кэш-системы XenonCache v2.1. Оно описывает процедуры диагностики и контроля работоспособности с помощью программы xenon-diag, входящей в поставку XenonCache.

Для полного выполнения задач технического обслуживания дополнительно используются следующие документы:

Наименование документаОбозначениеПримечание
Руководство оператораРО-XC-2.1Содержит описание интерфейсов управления и мониторинга
Описание примененияОП-XC-2.1Условия интеграции, сценарии использования
Программа и методика испытанийПМИ-XC-2.1Испытания при приёмке
Спецификация HTTP APISPEC-XC-HTTP-v2OpenAPI 3.1, доступна по /openapi.json
Инструкция по развёртываниюDEPLOY-XC-K8SДля окружения Kubernetes

2. Общие указания

Техническое обслуживание XenonCache выполняется с периодичностью:

  • Ежедневно: лёгкая диагностика (xenon-diag --mode quick);
  • Еженедельно: полная диагностика (xenon-diag --mode full --replicas all);
  • По требованию: после сбоя, перед обновлением, при расширении кластера.

Порядок проведения:

  1. Подготовка

    • Убедиться, что все узлы в состоянии Ready (kubectl get nodes).
    • Перевести кластер в режим обслуживания (через PUT /api/v1/maintenance?enable=true).
    • Проверить наличие свободного дискового пространства (df -h /var/lib/xenon ≥ 20%).
  2. Запуск диагностики

    • Выполнить xenon-diag с нужным режимом (см. п. 4.3).
    • Сохранить выходные данные в архив (/var/log/xenon/diag/YYYYMMDD_HHMM.tar.gz).
  3. Анализ результатов

    • Проверить код возврата (см. табл. 4.3.1).
    • При коде ≥ 1 — свериться с таблицей ошибок (прил. A).
    • При выявлении проблем — выполнить рекомендации из раздела 4.2.
  4. Завершение

    • Отключить режим обслуживания (PUT /api/v1/maintenance?enable=false).
    • Заархивировать отчёт и передать в систему учёта инцидентов (Jira, проект XC-OPS).

Квалификационные требования к персоналу:

  • Инженер по эксплуатации (категория не ниже 2-й),
  • Допуск к консоли управления,
  • Опыт работы с kubectl, systemd, journalctl,
  • Знание принципов распределённых систем (кворум, репликация, шардирование).

3. Требования к техническим средствам

Программа xenon-diag может быть запущена на любом узле кластера XenonCache, где установлен агент xenon-agent >= 2.1.0. Минимальная конфигурация:

КомпонентТребованиеОбоснование
Операционная системаUbuntu 22.04 LTS / Rocky Linux 9 / RHEL 9Поддержка systemd, cgroup v2
Ядро Linux≥ 5.15Требуется io_uring и memfd_create
Процессорx86_64 или arm64/v8, 2+ ядраПараллельная проверка шардов
Оперативная память4 ГБ (при кластере ≤ 10 узлов)Буферизация метаданных диагностики
Дисковое пространство1 ГБ свободно на /varЛоги, временные файлы, отчёты
Сетевые интерфейсыlo, активный eth0, IPv4/IPv6Внутрикластерная коммуникация
Зависимостиbash ≥ 4.4, jq ≥ 1.6, curl ≥ 7.74, python3.10Обработка JSON, HTTP-клиент
ПраваПользователь xenon в группах adm, dockerБезопасный доступ к сокетам

Примечание: Запуск от root запрещён. Программа использует CAP_NET_ADMIN и CAP_SYS_PTRACE через ambient capabilities (см. systemd unit).


4. Описание функций

4.1. Максимальный состав технических средств, проверяемых программой

Программа xenon-diag поддерживает диагностику следующих компонентов:

КомпонентМаксимальная конфигурацияПримечание
Узлы XenonCacheдо 64 узлов в одном кластереТопология: mesh или star
Хранилищаmem://, ssd://, nvme://, ramdisk://Только локальные устройства
Сетевые интерфейсыдо 8 интерфейсов на узелВключая VLAN, VRF
Внешние сервисыconsul, etcd, prometheus, lokiТолько read-only проверки подключения
ОборудованиеSMART-статус дисков, температура CPU (через ipmi-sensors)При наличии ipmi и прав sudo diag-ipmi

4.2. Совместное функционирование и обработка ошибок

Программа работает в два этапа:

  1. Сбор метаданных
    Выполняется параллельно по всем узлам через gRPC-канал к xenon-agent.
    Запросы:

    • /healthz (HTTP 200 OK),
    • /metrics?name=alloc_bytes (Prometheus-формат),
    • GET /v1/shards?state=all (состояние шардов).
  2. Исполнение проверок
    На каждом узле запускаются локальные скрипты (в chroot-окружении):

    • Проверка целостности индексов (crc32 хэш-свёртка),
    • Тест latency: 10 000 GETSETDEL (в памяти),
    • Проверка диска: fio --name=diag --rw=randread --bs=4k --size=64M.

Метод обработки ошибок:

Тип ошибкиОбработка
Сетевая недоступность узлаПовтор 2 раза с backoff=2^i * 500ms. При 3 отказах — статус UNREACHABLE, исключить из диагностики, отправить alert.
Несовпадение контрольной суммыЗаписать в отчёт checksum_mismatch: {shard_id, expected, actual}. Рекомендуется xenon-repair --shard <id>.
Таймаут операции (> 30s)Прервать поток, зафиксировать timeout_in_phase: <phase_name>, продолжить остальные проверки.
Отказ оборудования (SMART Reallocated_Sector_Ct > 0)Установить статус HW_DEGRADED, рекомендовать замену диска в ближайшие 72 ч.

✅ Все ошибки логируются в структурированном формате JSON (см. 4.3).

4.3. Организация входных и выходных данных

Входные данные:
  • CLI-аргументы:
    xenon-diag \
    --mode <quick|full> \
    --nodes <node1,node2,...|all> \
    --timeout <sec> \
    --output <json|text|both> \
    --log-level <error|warn|info|debug>
  • Переменные окружения (приоритет ниже CLI):
    XENON_DIAG_MODE=full
    XENON_DIAG_NODES=all
    XENON_DIAG_OUTPUT_DIR=/var/log/xenon/diag
Выходные данные:
  • Стандартный вывод (stdout): краткий отчёт в text (если --output=text или both).
  • Файл <timestamp>.json: полный отчёт в формате:
    {
    "version": "2.1.3",
    "run_id": "diag-20251111T1420Z",
    "cluster_id": "xc-prod-eu1",
    "timestamp": "2025-11-11T14:20:03Z",
    "mode": "full",
    "summary": {
    "nodes_total": 12,
    "nodes_ok": 11,
    "nodes_failed": 1,
    "shards_checked": 96,
    "shards_corrupted": 0,
    "exit_code": 1
    },
    "nodes": [
    {
    "id": "node-07",
    "status": "UNREACHABLE",
    "error": "connection refused: 10.42.7.15:8080"
    }
    ]
    }
Коды возврата:
КодЗначениеДействие
0Все проверки пройденыШтатная работа
1Предупреждения (нестабильность, деградация)Проверить логи, запланировать вмешательство
2Критические ошибки (потеря данных, неработоспособность узла)Немедленное вмешательство
3Ошибки среды (недостаточно прав, отсутствуют зависимости)Исправить окружение, повторить
255Внутренняя ошибка программыОбратиться к разработчикам, приложить лог --log-level=debug

4.4. Взаимодействие устройств с программой и вывод результатов

  • Программа не модифицирует состояние системы — только чтение и временные операции в памяти.
  • Взаимодействие с оборудованием:
    • Диски: через libatasmart и smartctl (только READ DATA, SMART READ ATTRIBUTE),
    • Сеть: через AF_PACKET сокеты (только recv для latency-проверок),
    • CPU: через /proc/cpuinfo, /sys/class/thermal.
  • Результаты выводятся:
    • В stdout (если --output=text),
    • В файлы *.json и *.log (автоматически, в XENON_DIAG_OUTPUT_DIR),
    • В syslog (приоритет LOG_NOTICE для exit_code=0, LOG_ERR — для ≥2),
    • В Prometheus Pushgateway (если PUSHGATEWAY_URL задан): метрика xenon_diag_last_run_status{mode="full"} = 0|1|2.

📌 Пример вывода stdout (--mode quick):

[INFO] XenonDiag v2.1.3 starting (mode=quick, nodes=12)
[OK] node-01..node-06: latency < 2ms
[OK] node-07: skipped (maintenance mode)
[WARN] node-08: disk I/O latency 15ms (threshold=10ms)
[OK] All shards healthy (96/96)
[SUMMARY] exit_code=1 (warnings present)

5. Проверочный чек-лист по заполнению РТО

Используйте этот список до сдачи документа в версионирование. Каждый пункт — обязательное требование ГОСТ или критически важная практика.

✅ Структура и оформление

  • Титульный лист содержит наименование, обозначение, дату, разработчика
  • Аннотация присутствует (3–5 предложений), отражает назначение и аудиторию
  • Содержание актуально и соответствует нумерации разделов
  • Все разделы пронумерованы по ГОСТ 19.105-78 (1, 1.1, 1.2, …)
  • Документ оформлен в соответствии с корпоративным стилем (шрифты, поля, колонтитулы)

✅ Содержание по требованиям ГОСТ 19.508-79

  • Раздел «Введение» содержит назначение и перечень сопутствующих документов
  • Раздел «Общие указания» описывает порядок, организацию и особенности проведения ТО
  • Раздел «Требования к техническим средствам» указывает минимальный состав, обеспечивающий работу программы
  • Раздел «Описание функций» включает:
    • максимальный состав проверяемых технических средств
    • описание совместного функционирования и метод обработки ошибок
    • организацию входных и выходных данных
    • взаимодействие устройств с программой и вывод результатов

✅ Техническая точность и безопасность

  • Все версии ПО/ОС/зависимостей указаны точно, с ограничениями (>=, <)
  • Приведены коды возврата с расшифровкой
  • Есть хотя бы один рабочий пример запуска (CLI или HTTP)
  • Указаны требования к квалификации персонала
  • Присутствуют меры безопасности (права, режимы запуска, запреты)
  • Все действия обратимы или идемпотентны (если применимо)

✅ Актуальность и поддержка

  • В титуле/шапке указана актуальная версия системы, для которой документ применим
  • Есть ссылка на процесс актуализации (например: «Обновляется при каждом minor-релизе»)
  • Документ прошёл техническое ревью разработчиком и эксплуатацией
  • Протестирован на стенде («сухой прогон» инструкций)

📎 Совет: интегрируйте этот чек-лист в CI/CD: при пуше в docs/ — запускайте markdownlint, vale, и семантическую проверку по шаблону (например, через jq на наличие ключевых полей в метаданных).